package com.southminority.ethnic.service.document;

import com.southminority.ethnic.common.result.PageResult;
import com.southminority.ethnic.dto.DocumentDTO;
import com.southminority.ethnic.controller.document.vo.DocumentVO;
import com.southminority.ethnic.controller.document.vo.FileTypeInfoVO;
import com.southminority.ethnic.vo.ShareInfoVO;

import java.util.List;

/**
 * 古籍文献服务接口
 * <p>
 * 定义了古籍文献模块的核心业务逻辑，包括前端展示和后台管理的所有功能。
 * 
 * @author SouthMinority
 */
public interface DocumentService {

    // =================================================================================
    // ==                             前端展示相关方法 (Public API)                     ==
    // =================================================================================

    /**
     * 获取首页推荐的特色古籍文献。
     * <p>
     * 通常返回 `is_featured` 为true且 `homepage_order` 最小的一条记录。
     *
     * @return {@link DocumentVO} 首页特色文献的视图对象，如果不存在则可能返回null或抛出异常。
     */
    DocumentVO getFeaturedDocument();

    /**
     * 获取所有设置为在首页展示的古籍文献列表。
     * <p>
     * 查询 `is_featured` 为true的记录，并根据 `homepage_order` 字段升序排序。
     *
     * @return {@link List<DocumentVO>} 首页展示的文献列表。
     */
    List<DocumentVO> getHomepageDocumentList();

    /**
     * 根据ID获取单个古籍文献的详细信息。
     *
     * @param id 古籍文献的唯一标识ID。
     * @return {@link DocumentVO} 包含文献所有详细信息的视图对象。
     */
    DocumentVO getDocumentDetail(Long id);

    /**
     * 获取所有已发布的古籍文献列表（不分页）。
     *
     * @return {@link List<DocumentVO>} 所有已发布文献的列表。
     */
    List<DocumentVO> getDocumentList();

    /**
     * 根据分类ID获取该分类下的所有古籍文献列表。
     *
     * @param categoryId 分类的唯一标识ID。
     * @return {@link List<DocumentVO>} 指定分类下的文献列表。
     */
    List<DocumentVO> getDocumentListByCategory(Long categoryId);

    /**
     * 根据文献类型（如古籍、手稿）获取古籍文献列表。
     *
     * @param documentType 文献类型字符串。
     * @return {@link List<DocumentVO>} 指定文献类型的列表。
     */
    List<DocumentVO> getDocumentListByType(String documentType);

    /**
     * 根据朝代获取古籍文献列表。
     *
     * @param dynasty 朝代名称字符串。
     * @return {@link List<DocumentVO>} 指定朝代的文献列表。
     */
    List<DocumentVO> getDocumentListByDynasty(String dynasty);

    /**
     * 根据关键词搜索古籍文献。
     * <p>
     * 搜索范围通常包括标题、作者、描述、关键词等字段。
     *
     * @param keyword 用户输入的搜索关键词。
     * @return {@link List<DocumentVO>} 符合搜索条件的文献列表。
     */
    List<DocumentVO> searchDocuments(String keyword);

    /**
     * 为指定的古籍文献增加一次浏览次数。
     *
     * @param id 古籍文献的唯一标识ID。
     */
    void increaseViewCount(Long id);

    /**
     * 为指定的古籍文献增加一次下载次数。
     *
     * @param id 古籍文献的唯一标识ID。
     */
    void increaseDownloadCount(Long id);

    /**
     * 获取指定古籍文献所有可用的文件类型信息。
     * <p>
     * 返回一个对象，其中包含PDF、图片、音视频等文件的存在状态和URL。
     *
     * @param id 古籍文献的唯一标识ID。
     * @return {@link FileTypeInfoVO} 文件类型信息的视图对象。
     */
    FileTypeInfoVO getDocumentFileTypes(Long id);

    /**
     * 为指定的古籍文献生成分享所需的信息。
     * <p>
     * 包括分享链接、标题、描述和二维码URL等。
     *
     * @param id 古籍文献的唯一标识ID。
     * @return {@link ShareInfoVO} 分享信息的视图对象。
     */
    ShareInfoVO generateShareInfo(Long id);


    // =================================================================================
    // ==                             后台管理相关方法 (Admin API)                      ==
    // =================================================================================

    /**
     * 分页查询古籍文献，支持多条件筛选。
     *
     * @param page         当前页码。
     * @param size         每页显示数量。
     * @param keyword      搜索关键词（可选）。
     * @param categoryId   分类ID（可选）。
     * @param documentType 文献类型（可选）。
     * @param dynasty      朝代（可选）。
     * @param status       状态（可选）。
     * @return {@link PageResult<DocumentVO>} 封装了分页信息和数据的查询结果。
     */
    PageResult<DocumentVO> getDocumentPage(Integer page, Integer size, String keyword, Long categoryId, String documentType, String dynasty, Integer status);

    /**
     * 创建一篇新的古籍文献。
     *
     * @param documentDTO 包含古籍文献所有信息的DTO对象。
     * @return {@link DocumentVO} 创建成功后返回的文献视图对象。
     */
    DocumentVO createDocument(DocumentDTO documentDTO);

    /**
     * 更新一篇已存在的古籍文献。
     *
     * @param id          要更新的古籍文献的ID。
     * @param documentDTO 包含更新后信息的DTO对象。
     * @return {@link DocumentVO} 更新成功后返回的文献视图对象。
     */
    DocumentVO updateDocument(Long id, DocumentDTO documentDTO);

    /**
     * 根据ID删除一篇古籍文献（通常是逻辑删除）。
     *
     * @param id 要删除的古籍文献的ID。
     * @return 如果删除成功返回true，否则返回false。
     */
    boolean deleteDocument(Long id);

    /**
     * 批量删除古籍文献。
     *
     * @param ids 包含多个要删除的古籍文献ID的列表。
     * @return 如果操作成功返回true，否则返回false。
     */
    boolean batchDeleteDocument(List<Long> ids);

    /**
     * 更新指定古籍文献的状态。
     *
     * @param id     古籍文献的ID。
     * @param status 新的状态值（例如：1-已发布, 0-草稿, -1-已删除）。
     * @return 如果更新成功返回true，否则返回false。
     */
    boolean updateDocumentStatus(Long id, Integer status);

    /**
     * 设置或取消古籍文献的首页展示。
     *
     * @param id         古籍文献的ID。
     * @param isFeatured 是否在首页展示（1-是, 0-否）。
     * @return 如果设置成功返回true，否则返回false。
     */
    boolean setDocumentFeatured(Long id, Integer isFeatured);

    /**
     * 设置古籍文献在首页的展示顺序。
     *
     * @param id            古籍文献的ID。
     * @param homepageOrder 首页展示的排序号，数字越小越靠前。
     * @return 如果设置成功返回true，否则返回false。
     */
    boolean setDocumentHomepageOrder(Long id, Integer homepageOrder);

    /**
     * 获取所有古籍文献的列表（不分页），主要用于后台管理的一些选择场景。
     *
     * @return {@link List<DocumentVO>} 包含所有文献的列表。
     */
    List<DocumentVO> getAllDocumentList();
} 
